<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>lua_opcall</title>
    <link rel="stylesheet" type="text/css" href="csound.css" />
    <meta name="generator" content="DocBook XSL Stylesheets V1.78.1" />
    <link rel="home" href="index.html" title="The Canonical Csound Reference Manual" />
    <link rel="up" href="OpcodesTop.html" title="Orchestra Opcodes and Operators" />
    <link rel="prev" href="lua_opdef.html" title="lua_opdef" />
    <link rel="next" href="mac.html" title="mac" />
  </head>
  <body>
    <div class="navheader">
      <table width="100%" summary="Navigation header">
        <tr>
          <th colspan="3" align="center">
            lua_opcall
        </th>
        </tr>
        <tr>
          <td width="20%" align="left"><a accesskey="p" href="lua_opdef.html">Prev</a> </td>
          <th width="60%" align="center">Orchestra Opcodes and Operators</th>
          <td width="20%" align="right"> <a accesskey="n" href="mac.html">Next</a></td>
        </tr>
      </table>
      <hr />
    </div>
    <div class="refentry">
      <a id="lua_opcall"></a>
      <div class="titlepage"></div>
      <a id="Indexlua_opcall" class="indexterm"></a>
      <div class="refnamediv">
        <h2>
          <span class="refentrytitle">
            lua_opcall
        </span>
        </h2>
        <p>
            lua_opcall
         — 
            Calls a Lua opcode at i-rate only. Any number of output and/or 
            input arguments may be passed. All arguments must be passed on 
            the right-hand side. Outputs are returned in the argument.        
        </p>
      </div>
      <div class="refsect1">
        <a id="idp122098656"></a>
        <h2>
            Syntax
        </h2>
        <pre class="synopsis"><span class="command"><strong>lua_iopcall</strong></span> Sname, ...</pre>
        <pre class="synopsis"><span class="command"><strong>lua_ikopcall</strong></span> Sname, ...</pre>
        <pre class="synopsis"><span class="command"><strong>lua_iaopcall</strong></span> Sname, ...</pre>
        <pre class="synopsis"><span class="command"><strong>lua_iopcall_off</strong></span> Sname, ...</pre>
        <pre class="synopsis"><span class="command"><strong>lua_ikopcall_off</strong></span> Sname, ...</pre>
        <pre class="synopsis"><span class="command"><strong>lua_iaopcall_off</strong></span> Sname, ...</pre>
      </div>
      <div class="refsect1"><a id="idp122179344"></a><h2>
            Initialization and Performance
        </h2><p>
            <span class="emphasis"><em>Sname</em></span> -- The name of the opcode.
        </p><p>
            <span class="emphasis"><em>...</em></span> -- An arbitrary list of any number of 
            output and input arguments, of any type. The number, sequence, 
            and types of these arguments must agree with the cdef of the 
            arguments structure that is declared in the corresponding 
            <code class="literal">lua_opdef</code> opcode.
        </p><p>
            <code class="literal">lua_iopcall</code> calls a Lua opcode at i-rate only. 
            Requires <code class="literal">opname_init</code> to be defined in Lua.
        </p><code class="literal">lua_ikopcall</code> calls a Lua opcode at i-rate and 
            k-rate. Requires <code class="literal">opname_init</code> and 
            <code class="literal">opname_kontrol</code> to be defined in Lua.
        <p>
            <code class="literal">lua_iaopcall</code> calls a Lua opcode at i-rate and a-rate. 
            Requires <code class="literal">opname_init</code> and 
            <code class="literal">opname_audio</code> to be defined in Lua.
        </p><p>
            <code class="literal">lua_iopcall_off</code> calls a Lua opcode at i-rate only. 
            Requires <code class="literal">opname_init</code> and 
            <code class="literal">opname_noteoff</code> to be defined in Lua. 
        </p><code class="literal">lua_ikopcall_off</code> calls a Lua opcode at i-rate and 
            k-rate. Requires <code class="literal">opname_init</code>, 
            <code class="literal">opname_kontrol</code>, and <code class="literal">opname_noteoff</code> 
            to be defined in Lua.
        <p>
            <code class="literal">lua_iaopcall_off</code> calls a Lua opcode at i-rate 
            and a-rate. Requires <code class="literal">opname_init</code>, 
            <code class="literal">opname_audio</code>, and <code class="literal">opname_noteoff</code> 
            to be defined in Lua.
        </p><p>
            Lua code accesses elements of arguments as follows (pointers 
            to both scalars and arrays are dereferenced by the Lua array access 
            operator):
        </p><pre class="programlisting">
            ffi.cdef(' struct arguments_t { double *a_out, double *i_in, double *i_txt, double *f_sig };');
            local arguments = ffi.cast("struct arguments_t *", carguments_lightuserdata)
            for i = 0, ksmps -1 do begin carguments.a_out[i] = carguments.i_in[0] * 3 end end
        </pre><p>
            The "off" variants of the opcode always schedule a "note off" event 
            that is called when the intrument instance is removed from the 
            active list, and which can be used to release unneeded resources, 
            reschedule the instrument to render a reverb tail, and so on.
        </p></div>
      <div class="refsect1">
        <a id="idp122200640"></a>
        <h2>
            Example
        </h2>
        <p>
            Here is an example of a Lua opcode, showing how to pass strings 
            back and forth between Lua opcodes and Csound orchestra code. 
            The example uses the file <a class="ulink" href="examples/luaopcode.csd" target="_top">
            <em class="citetitle">luaopcode.csd</em></a>.
            </p>
        <div class="example">
          <a id="idp122204032"></a>
          <p class="title">
            <strong>Example 463. 
                    Example of a Lua opcode.
                </strong>
          </p>
          <div class="example-contents">
            <pre class="programlisting">
<span class="csdtag">&lt;CsoundSynthesizer&gt;</span>
<span class="csdtag">&lt;CsInstruments&gt;</span>
<span class="opc">lua_opdef</span> "luatest", {{
local ffi <span class="op">=</span> require("ffi")
local string <span class="op">=</span> require("string")
local csoundLibrary <span class="op">=</span> ffi.load('csound64.dll.5.2')
ffi.cdef[[
    <span class="opc">int</span> csoundGetKsmps(void <span class="op">*</span>)<span class="comment">;</span>
    double csoundGetSr(void <span class="op">*</span>)<span class="comment">;</span>
    struct luatest_arguments {double <span class="op">*</span><span class="opc">out</span><span class="comment">; double *stringout; char *stringin; double *in1; double *in2; double sr; int ksmps; };</span>
]]
function luatest_init(csound, opcode, carguments)
    local arguments <span class="op">=</span> ffi.cast("struct luatest_arguments <span class="op">*</span>", carguments)
    arguments.sr <span class="op">=</span> csoundLibrary.csoundGetSr(csound)
    <span class="opc">print</span>(string.format('stringin<span class="op">:</span> <span class="op">%</span>s', ffi.string(arguments.stringin)))
    <span class="opc">print</span>(string.format('sr<span class="op">:</span> <span class="op">%</span>f', arguments.sr))
    arguments.ksmps <span class="op">=</span> csoundLibrary.csoundGetKsmps(csound)
    <span class="opc">print</span>(string.format('ksmps<span class="op">:</span> <span class="op">%</span>d', arguments.ksmps))
    arguments.out[0] <span class="op">=</span> arguments.in1[0] <span class="op">*</span> arguments.in2[0]
    ffi.copy(arguments.stringout, 'Hello, world!')
    <span class="opc">return</span> 0
end
function luatest_kontrol(csound, opcode, carguments)
    local arguments <span class="op">=</span> ffi.cast("struct luatest_arguments <span class="op">*</span>", carguments)
    arguments.out[0] <span class="op">=</span> arguments.in1[0] <span class="op">*</span> arguments.in2[0]
    <span class="opc">return</span> 0
end
function luatest_noteoff(csound, opcode, carguments)
    local arguments <span class="op">=</span> ffi.cast("struct luatest_arguments <span class="op">*</span>", carguments)
    arguments.out[0] <span class="op">=</span> arguments.in1[0] <span class="op">*</span> arguments.in2[0]
    <span class="opc">print</span>('off')
    <span class="opc">return</span> 0
end
}}

<span class="oblock">instr</span> 1
    iresult <span class="op">=</span> 0
    Stringin <span class="op">=</span> "stringin"
    Stringout <span class="op">=</span> "stringout"
    <span class="opc">lua_iopcall</span> "luatest", iresult, Stringout, Stringin, p2, p3
    <span class="opc">prints</span> Stringout
<span class="oblock">endin</span>
<span class="oblock">instr</span> 2
    iresult <span class="op">=</span> 0
    Stringin <span class="op">=</span> "stringin"
    Stringout <span class="op">=</span> "initial value"
    <span class="opc">lua_iopcall_off</span> "luatest", iresult, Stringout, Stringin, p2, p3
    <span class="opc">print</span> iresult
    <span class="opc">prints</span> Stringout
<span class="oblock">endin</span>
<span class="csdtag">&lt;/CsInstruments&gt;</span>
<span class="csdtag">&lt;CsScore&gt;</span>
<span class="stamnt">i</span> 1 1 2
<span class="stamnt">i</span> 2 2 2
<span class="stamnt">i</span> 1 3 2
<span class="stamnt">e</span>
<span class="csdtag">&lt;/CsScore&gt;</span>
<span class="csdtag">&lt;/CsoundSynthesizer&gt;</span>
</pre>
          </div>
        </div>
        <p><br class="example-break" />
        </p>
      </div>
      <div class="refsect1">
        <a id="idp122205824"></a>
        <h2>
            See Also
        </h2>
        <p>
            <a class="link" href="lua_exec.html" title="lua_exec"><em class="citetitle">lua_exec</em></a>, 
            <a class="link" href="lua_opdef.html" title="lua_opdef"><em class="citetitle">lua_opdef</em></a>. 
        </p>
      </div>
      <div class="refsect1">
        <a id="idp122208880"></a>
        <h2>
            Credits
        </h2>
        <p>
            By: Michael Gogins 2011
        </p>
        <p>
            New in Csound version 5.13.2
        </p>
      </div>
    </div>
    <div class="navfooter">
      <hr />
      <table width="100%" summary="Navigation footer">
        <tr>
          <td width="40%" align="left"><a accesskey="p" href="lua_opdef.html">Prev</a> </td>
          <td width="20%" align="center">
            <a accesskey="u" href="OpcodesTop.html">Up</a>
          </td>
          <td width="40%" align="right"> <a accesskey="n" href="mac.html">Next</a></td>
        </tr>
        <tr>
          <td width="40%" align="left" valign="top">
            lua_opdef
         </td>
          <td width="20%" align="center">
            <a accesskey="h" href="index.html">Home</a>
          </td>
          <td width="40%" align="right" valign="top"> mac</td>
        </tr>
      </table>
    </div>
  </body>
</html>
